Function            litebar_alloc - allocate memory for a litebar
                                        menu

  Syntax              struct litebar_header *litebar_alloc(int left, int
                                top, int right, int bottom, char *frame,
                                char *title, int titlejustify, int count,
                                char *command[], int cmdleft[], int
                                cmdright[], int cmdup[], int cmddown[],
                                int cmdkey[], char cmdflag[], int cmdx[],
                                int cmdy[], char *message[], int msgx,
                                int msgy, int argq, int quitkey[], int
                                colframe, int coltitle, int colnorm, int
                                colcmdkey, int colhilite, int coldisable,
                                int coldishilite, int colnotopt, int
                                colmessage, int defaultcommand, unsigned
                                flags);

  Prototype in        menuhk.h

  Remarks             litebar_alloc creates a litebar menu with the
                      following information:

                      Coordinates of the frame of the litebar menu are
                      (left,top) to (right,bottom), the border, if any,
                      is made up of the 9 or 11 chars in frame (0 to 8 or
                      10) as per boxwindow(), with an optional title on
                      the top edge of the menu border, justified left,
                      right or center (see howard.h for more details). If
                      frame == NULL  there will be no border. If
                      titlejustify = NONE there will be no title, or
                      pre-/post-title separators.

                      Unlike the popup menus, a count parameter is
                      required, specifiying how many commands there are.
                      The command array is a list of strings or text to
                      be displayed on the screen.

                      The cmdleft, cmdright, cmdup and cmddown parameters
                      are lists of where the respective key will move the
                      hilite bar. These values should correspond to an
                      index of the command[], with the exception noted
                      below. For example, if the hilite bar is on
                      command[0] and you wish the right arrow to move to
                      command[10], then cmdright[0] = 10. The exception
                      is when an arrow is to be disabled. Specifying a -1
                      as a direction element will disable that direction
                      for that command (i.e. at command[0] to make the
                      left arrow do nothing, then cmdleft[0] = -1.)

                      Each command can have a hotkey associated with it,
                      denoted by the appropriate cmdkey[]. The 'hotkey'
                      is actually a one-touch key, instantly moving to
                      and selecting a choice. The cmdkey value is an
                      offset into the command string. For example, a
                      command "Edit" with a hotkey of the "E" would have
                      a cmdkey value of 0 (an offset from the beginning
                      of the command). A command without a hotkey has a
                      cmdkey value of -1.

                      Each command has an appropriate cmdflag field. A
                      command may be either:

                           ENABLED     - a valid choice
                           DISABLED    - displayed, but not selectable
                           NOTOPTION   - not a command (static text)

                      These are defined in menuhk.h. Other values may
                      cause unpredictable results.

                      The cmdx and cmdy arrays are lists of where the
                      commands should be displayed, respective to the
                      box. This is in a 'windowing' sense. If the box
                      coordinates are (10,10) to (20,20) and you wish
                      something to appear at the physical coordinates
                      (12,10) then (cmdx,cmdy) for the proper command
                      should be (2,0). This is an exception to the normal
                      coordinate system beginning at (1,1). In a litebar
                      menu, the 'border' is not excluded from the display
                      output and can be written over (this is true
                      regardless of whether or not a frame is displayed.)

                      TCHK litebar menus can display a message for each
                      command as it is hilited, much like Lotus style
                      menus. This message is optional, and if the
                      appropriate message[] is not NULL, it will be
                      displayed at (msgx,msgy). If the message[] element
                      is NULL, no message will be displayed. These
                      coordinates are relative to the menu coordinates,
                      just as cmdx and cmdy are.

                      A list of key codes that cause immediate return of
                      the user selection of the menu are in the quitkey
                      list, consisting of argq elements.

                      The following colors are used:

                           colframe       - frame around menu (if any)
                           coltitle       - title (if any)
                           colnorm        - enabled commands
                           colcmdkey      - hotkey in command
                           colhilite      - currently hilited option
                           coldisable     - disabled options
                           coldishilite   - disabled and currently
                                            hilited
                           colnotopt      - static text (NOTOPTION)
                           colmessage     - message (if any)

                      defaultcommand is the command initially hilited. If
                      an invalid command is chosen (the command is static
                      text, or does not exist, etc.) the first valid
                      command is the default.

                      flags is a 2-byte bit field of flags

                           QEFxxxxH UDIRCEDW

                      where

                           Q = Quit after selection
                           E = ESC means quit
                           F = Free memory on quit
                           H = Hierarchial menu (not implemented yet)

                           U = call _idle_menu() after keyboard input
                           D = free time slices under DESQview
                           I = cmdkeys are case Independent
                           R = Restore cursor before returning
                           C = don't hide Cursor
                           E = Erase menu on free/cleanup
                           D = Disabled not hiliteable
                           W = Wraparound

                      Briefly, Quit will restore the display to the state
                      it was in before the litebar menu was called
                      (settextinfo(), etc.). With E, if ESC is pressed
                      the menu is removed, for any other selection no
                      cleanup is done (unless Q is specified). Free
                      memory on quit calls litebar_free() after a
                      selection is made. Hierarchial menus are not
                      implemented yet. Keys are input via inkey(),
                      inkeyc(), inkeydv() or inkeycdv(), depending on
                      case Independency and freeeing time slices under
                      DESQview. When litebar_get() is called, the cursor
                      is hidden unless C is given. The cursor is unhidden
                      only if R is given. E will cause the menu to be
                      erased from the screen if quitting. Disabled
                      commands are normally selectable, unless D is on.
                      Wraparound allows the selecting hilite bar to wrap
                      over the top and under the bottom.

                      After input is polled, if the user defined function
                      flag is set (UDFIDLE) the function _idle_menu is
                      called. Currently, the definition of _idle_menu is:

                                int _idle_menu(void)

                      Possible uses for such a function is an onscreen
                      clock, printing, or some other background task. In
                      the future _idle_menu() will receive releveant
                      parameters. To define _idle_menu as the user
                      defined function int myfunction(void), try:

                           _idle_menu = (far *)myfunction;

                      The full definition for _idle_menu() is:

                           int (far *_idle_menu)(void);

                      You should declare myfunction() as type int, with
                      void parameters, and you should typecast the
                      function as a far pointer when you assign it to
                      _idle_menu.

  Return value        allocates and returns a pointer to a litebar header
                      structure if the menu was successfully created,
                      otherwise returns NULL if an error occurred.
                      litebarerrno will have the following values:

                           0    success
                           1    error, could not allocate litebar header
                           2    error, could not allocate videosave
                           3    error, could not allocate menusave
                           4    error, invalid title justification
                           5    error, could not allocate popup field
                           7    error, no menu item enabled (no commands)
                           8    error, could not allocate quit keylist

  Note                The litebar_header structure contains important
                      information about the menu, including pointers to
                      linked lists for the fields, saved video displays,
                      etc. I strongly advise that you don't even think of
                      modifying this information yourself. Let the
                      litebar...() functions handle it for you. These
                      functions have been developed and used over a
                      period of several months, programs and conditions
                      which proves them to be virtually bug free. If you
                      really want to mess with them yourself, feel free.
                      But I certainly wouldn't want to attempt it.
                      Modifying these functions even with the source code
                      is a headache.

  See also            menuhk.h
                      changelitebar(), isHiliteable(), litebar_free(),
                      litebar_get(), litehilite(), litemessage(),
                      liteunlite(), menu_litebar()
                      litebarerrno

  Example             see demolite.c